The CICA Windows Explosion!/The CICA Windows Explosion! - Disc 2.iso/demo/wemdemo4.zip/INFO/W3.1

GNU Info File | 1994-09-21 | 50KB | 897 lines

This is Info file ../info/w3, produced by Makeinfo-1.56 from the input
file w3.txi.
   This file documents the Emacs-w3 World Wide Web browser.
   Copyright (C) 1993, 1994 William M. Perry
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
File: w3,  Node: Top,  Next: Introduction,  Up: (DIR)
   This manual documents the Emacs-w3 World Wide Web browser, a Lisp
program which runs as a subsystem under Emacs.  The manual is divided
into the following chapters.
* Menu:
* Introduction::                What exactly is Emacs-w3?
* Setting Up::                  How to set up and install Emacs-w3.
* Basic Usage::                 Basic movement and usage of Emacs-w3.
* Compatibility w/Mosaic::      Explanation of how Emacs-w3 is compatible
                                with NCSA Mosaic for Xwindows.
* Controlling Formatting::    How to control how Emacs-w3 formats HTML
* HTTP/1.0 Support::        A detailed explanation of the HTTP/1.0
                and MIME support in Emacs-w3.
* Advanced Features::           Some of the more arcane features.
* More Help::                   How to get more help--mailing lists,
                                newsgroups, etc.
* Future Directions::           What is planned for future revisions
                                of Emacs-w3
* Programming Interface::       How to use emacs-w3 from other emacs
                                programs.
Indices:
* Concept Index::               Concept Index
* Key Index::                   Menus of command keys and their references
* Command Index::               Menus of commands and their references
* Variable Index::              Menus of variables and their references
File: w3,  Node: Introduction,  Next: Setting Up,  Prev: Top,  Up: Top
Introduction
************
   Emacs-w3 is an Emacs subsystem that allows the user to browse the
wonderful World Wide Web.
   The World Wide Web was started at the CERN physics institute in
Switzerland in 1991.  The project was initially started by Tim
Berners-Lee ([e-mail]) for distributing data between
different research groups effectively.
   The Web has since grown into the most advanced information system
currently on the internet.  It is now a global hypertext system with
servers and browsers (programs written to interpret the hypertext
language and display it correctly, and allow the user to follow links)
exist for all major platforms (VMS, Windows, DOS, Unix, VM, NeXTstep,
and Macintosh).
   The basic concepts used in the Web are hypertext and hypermedia.
Hypertext is the same as regular text, with one exception--it can
contain links (cross-references) to other textual documents.  Hypermedia
is slightly different--it can contain links to other forms of media
(movies, sounds, interactive programs, etc.).
   WWW also allows searches of indices that are located anywhere on the
network; in this respect, it mirrors certain capabilities found in both
WAIS and Gopher.
                            ---------------
                           CLIENT SIDE VIEW
                            ---------------
   The WWW world consists of documents, and links.  Indexes are special
documents which, rather than being read, may be searched.  The result of
such a search is another virtual document containing links to the
documents found.  A simple protocol, HTTP is used to allow a browser
program to request a keyword search by a remote information server.
   The web contains documents in many formats.  Those documents which
are hypertext, (real or virtual) contain links to other documents, or
places within documents.  All documents, whether real, virtual or
indexes, look similar to the reader and are contained within the same
addressing scheme.
                       ------------------------
                       INFORMATION PROVIDER VIEW
                       ------------------------
   The WWW browsers can access many existing data systems via existing
protocols (FTP, NNTP) or via HTTP and a gateway.  In this way, the
critical mass of data is quickly exceeded, and the increasing use of the
system by readers and information suppliers encourage each other.
   Providing information is as simple as running the WWW server and
pointing it at an existing directory structure.  The server
automatically generates the a hypertext view of the files to guide the
user around.
   To personalize it, a few SGML hypertext files can be written to give
an even more friendly view.  Also, any file available by anonymous FTP,
or any internet newsgroup can be immediately linked into the web.  The
very small start-up effort is designed to allow small contributions.  At
the other end of the scale, large information providers may provide an
HTTP server with full text or keyword indexing.  This may allow access
to a large existing database without changing the way that database is
managed.  Such gateways have already been made into Oracle(tm), WAIS,
and Digital's VMS/Help systems, to name but a few.
   The WWW model gets over the frustrating incompatibilities of data
format between suppliers and reader by allowing negotiation of format
between a smart browser and a smart server.  This should provide a
basis for extension into multimedia, and allow those who share
application standards to make full use of them across the web.
   Here is some more specific information about what Emacs-w3 does and
does not understand:
* Menu:
* Markup Languages Supported::    The different markup languages that
                Emacs-w3 understands natively.
* Supported Protocols::        The different network protocols that
                Emacs-w3 speaks to.
File: w3,  Node: Markup Languages Supported,  Next: Supported Protocols,  Prev: Introduction,  Up: Introduction
Supported Markup Languages
**************************
   Two different markup languages are supported by Emacs-w3.
                               ---------
                                 HTML
                               ---------
   HTML is composed of a set of elements that define a document and
guide its display.  An HTML element may include a name, some attributes
and some text or hypertext, and appears in an HTML document as
<tag_name>text</tag_name>, <tag_name
attribute_name=argument>text</tag_name>, or just <tag_name>.
   For example: `<title> My Useful Document </title>', and `<pre
width=60> A lot of text here.  </pre>'.
   An HTML document is composed of a single element: <html>...</html>,
that is, in turn, composed of head and body elements: <head>...</head>,
and <body>...</body>.  To allow older HTML documents to remain readable,
<html>, <head>, and <body> are actually optional within HTML documents.
   All the tags and attributes of HTML are fully supported in Emacs-w3.
                               ---------
                                 HTML+
                               ---------
   The HTML+ language is an extension of HTML, with a large degree of
backwards compatibility.  See the internet draft by Dave Raggett for
more information.  The following HTML+ language elements are supported
by Emacs-w3:
   * FORMS - forms are one of the most powerful aspects of HTML+.  They
     allow the author of an HTML document to request information from
     the person viewing the document.  Passwords, checkboxes, radio
     buttons, and many more types of entry fields are possible.
     Emacs-w3 supports all the input tags, as well as GET and POST
     submission methods.  Emacs-w3 also supports the Mosaic 2.0 hack of
     automatically submitting forms with a NAME of isindex.
   * ID tags for headers and paragraphs.  This makes it possible to
     reference points within a document and not require empty hypertext
     links to do it.
   * LINK support.  LINKs allow the author to specify the relevance
     between documents easily.  This makes it possible to point to
     dictionaries, glossaries, or indices, or to specify the author of
     a document.
   * Annotations.  Can have <footnote> and <margin> notes that show up
     as footnotes at the bottom of a document.
   * BR tag for explicit line breaks
   * Notes and admonishments.  A way to specify a warning or other
     standard information.  Shows appropriate bitmap if possible.
     Similar to warning dialogs in Windows/Macintosh.
   * Infinitely nested lists, and use of paragraphs and headers within
     lists.
                               ---------
                                Extras
                               ---------
   There are several different markup elements that are not officially
part of HTML or HTML+ that Emacs-w3 supports.  These are either items
that have been dropped from HTML+ because they would be too difficult
for other browsers to implement or have been moved into another tag.
   * RENDER support.  The render tag can be used to convert one tag into
     another.  Syntax is <RENDER TAG="PROPNAME" STYLE="I">, which
     replaces all <PROPNAME> tags with <I>, and all </PROPNAME> tags
     with </I>.
   * Entity definitions within documents.  This allows the author of an
     HTML page to define per-document macros.  Syntax is <!ENTITY TAG
     "Expansion of Tag">, which replaces all occurences of &TAG; with
     Expansion of Tag.
   * Roman numerals for ordered lists.  If an ordered list has an
     optional ROMAN attribute (`<OL ROMAN>', then roman numerals are
     used instead of normal arabic numbers.
   * IMG and ALT support for list items.  If a list item has an IMG or
     ALT tag (`<LI IMG="some.gif" ALT="text"'), then the list character
     is replaced with either an icon or the ALT text.
   * Specifying the hostname and port of an NNTP server in a news URL.
     URLs of the form news://hostname:port/messageID work.
File: w3,  Node: Supported Protocols,  Prev: Markup Languages Supported,  Up: Introduction
Supported Protocols
*******************
   Emacs-w3 supports the following protocols
Usenet News
     Can either display an entire newsgroup or specific articles by
     Message-ID: header.  This supports a unix-style .newsrc file, so
     the user does not see articles they have read using another
     newsreader, but due to how news URLs work, Emacs-w3 cannot update
     the users .newsrc after they have read news.
     Supports both the HTTP/0.9 and HTTP/1.0 protocols.  Fully
     MIME-compliant with regards to HTTP/1.0. *Note HTTP/1.0 Support::
Gopher
     Support for all gopher types, include CSO searches.
Gopher+
     Support for Gopher+ retrievals. Support for converting ASK blocks
     into HTML+ FORMS and submitting them back to the server.
     FTP is handled by either ange-ftp or efs, the choice is up to the
     individual user.
Local files
     Local files are handled, and MIME content-types are derived from
     the file extensions.
Telnet
     Telnet is handled by running the Emacs Lisp function `telnet', or
     spawning an xterm running telnet.
TN3270
     TN3270 is handled by running a tn3270 program in an Emacs buffer,
     or spawning an xterm running tn3270.
     Emacs-w3 supports the mailto: url scheme that causes a mail
     message to be started to a specific address.
X-exec
     A URL can cause a local executable to be run, and its output
     interpreted as if it had come from an HTTP server.  This is very
     useful, but is still an experimental protocol, hence the X- prefix.
Secure HTTP
     Work is in progress to add support for the Secure HTTP
     specification from Enterprise Information Technologies.  (1)
   ---------- Footnotes ----------
   (1)  The specification for SHTTP can be found on EIT's web server at
http://www.commerce.net/information/standards/drafts/shttp.txt
File: w3,  Node: Setting Up,  Next: Retrieving Emacs-w3,  Prev: Introduction,  Up: Top
Setting Up
**********
   This section of the manual deals with getting, compiling, and
configuring Emacs-w3.
* Menu:
* Retrieving Emacs-w3::         Retrieving Emacs-w3 via anonymous ftp
* Compiling Emacs-w3::          Compiling Emacs-w3 and its associated files
* Basic Setup::                 Basic setup that everyone needs to do
* Firewalls::                   How to set Emacs-w3 up to use a particular
                                firewall setup.
* Proxy Gateways::              Using CERN's proxy HTTP server
File: w3,  Node: Retrieving Emacs-w3,  Next: Compiling Emacs-w3,  Prev: Setting Up,  Up: Setting Up
Retrieving Emacs-w3
===================
   If using Lucid Emacs 19.9, skip to the section on starting Emacs-w3.
Emacs-w3 comes standard with all versions of Lucid Emacs from 19.9
onwards.
   Three files are required when first installing Emacs-w3.  All of them
can be found via anonymous ftp to ftp.cs.indiana.edu:/pub/elisp/w3.  The
files are `w3-XXX.tar.gz', where XXX is the version number of Emacs-w3
being retrieved, `icons.tar.gz', which contains approximately 50 small
icons that Emacs-w3 requires, and are available to HTML authors.  The
`extras.tar.gz' file contains ange-ftp, html-mode, and nntp.
   After retrieving the files, unpack them with the following commands:
`zcat w3-XXX.tar.gz | tar xvvf -', `zcat icons.tar.gz | tar xvvf -',
and `zcat extras.tar.gz | tar xvvf -'.  This unpacks the distribution
into three subdirectories `w3', `icons', and `extras'.  To compile and
install all the packages in the extras directory, please see the
comments at the top of each lisp file.
File: w3,  Node: Compiling Emacs-w3,  Next: Basic Setup,  Prev: Retrieving Emacs-w3,  Up: Setting Up
Compiling Emacs-w3
==================
   To install Emacs-w3, go into the `w3' subdirectory and edit the
`Makefile'.  Three variables need to be changed:
`EMACS'
     This variable controls what version of Emacs is used to compile the
     programs.  It should be the full path to the Emacs executable on
     the system.  The default is to use Lucid Emacs (`lemacs').
`LISPDIR'
     This variable controls where the lisp code is copied to when it is
     installed (with `make install').  This is usually the users
     personal lisp code directory (I prefer `~/lisp').  The value is run
     through "expand-file-name" and then added to the load-path.
`DOTEMACS'
     This variable points to the Emacs customization file, usually
     `~/.emacs'.
`INFODIR'
     This variable points to the local info directory (usually
     `/usr/local/info').  This can be any valid directory, as long as it
     is in `Info-default-directory-list' so that info-mode can find it.
`MAKEINFO'
     This variables controls how the info files are built.  Possible
     values are `makeinfo' or `emacs -batch -q -f batch-texinfo-format'.
Once the `Makefile' has been modified, several different targets can be
built.
`make w3'
     This compiles all the .el files into the much faster .elc files.
     If Jamie Zawinski's optimizing byte compiler (standard in GNU
     Emacs 19 and Lucid Emacs) is used, then a few compilation warnings
     are displayed (not many hopefully).  These can be safely ignored
     as long as everything finishes compiling.  This is the default
     target for `make' with no arguments.
`make install'
     Compiles all the .el files and copies .el and .elc files into the
     directory specified by `LISPDIR'.
`make emacs'
     Modifies the file specified by `DOTEMACS'.  A statement modifying
     the load-path variable and size autoload statements is added to
     the end of the file.
`make all'
     Compiles and installs the .el files, and also modify/create the
     `DOTEMACS' file.
`make w3.info'
     Creates the Emacs-readable info files.  The info files are created
     in the directory specified by `INFODIR'.  The makefile variable
     `MAKEINFO' determines how the info file is built.
`make w3.dvi'
     Creates the printable documentation, using tex and texindex to
     properly generate the indices.  A `w3.dvi' file is left in the
     current directory.
File: w3,  Node: Basic Setup,  Next: Firewalls,  Prev: Compiling Emacs-w3,  Up: Setting Up
Basic Setup
===========
   There are a few variables that almost all people need to change.
`url-bad-port-list'
     List of ports to warn the user about connecting to.  Defaults to
     just the mail and NNTP ports so a malicious HTML author cannot
     spoof mail or news to other people.
`url-be-asynchronous'
     Controls whether document retrievals over HTTP should be done in
     the background.  This allows emacs to keep working in other
     windows while large downloads occur.
`w3-confirmation-func'
     What function to use for asking yes or no functions.  Possible
     values are 'yes-or-no-p or 'y-or-n-p, or any function that takes a
     single argument (the prompt), and returns `t' only if a positive
     answer is gotten.
`w3-default-action'
     A lisp symbol specifying what action to take for files with
     extensions that are not in the w3-mime-extensions assoc list.
     This is useful in case Emacs-w3 ever run across files with weird
     extensions (.foo, .README, .READMEFIRST, etc.).  This should not
     be required anymore.
     Possible values: any lisp symbol.  Should be a function that takes
     no arguments.  The return value does not matter, it is ignored.
     Some examples are
          Action            Value
          ----------------------------------------------
          Parse as HTML        'w3-prepare-buffer
          View as text        'indented-text-mode
`w3-default-homepage'
     The url to open at startup.  It can be any valid URL.  This
     defaults to the environment variable WWW_HOME if it is not set it
     in the users `.emacs' file. If WWW_HOME is undefined, then it
     defaults to the hypertext documentation for Emacs-w3 at Indiana
     University.
`w3-delay-image-loads'
     Controls the loading of inlined images.  If non-`nil', images are
     not loaded.  For slow network connections, this is usually set to
     `t'.
`w3-delimit-emphasis'
     Whether to use characters at the start and end of each bold/italic
     region.  Types of characters are specified in
     `w3-style-chars-assoc'.  `w3-style-chars-assoc' is an assoc list
     of style names, the `cdr' of each is a cons cell.  The `car' of
     this cell is the string to insert at the beginning of the
     emphasis, and the `cdr' is the string to insert at the end of the
     emphasis.  The default value is a good example.
          (
           ("B"       "*"  . "*")
           ("ADDRESS" "*"  . "*")
           ("BYLINE"  "_"  . "_")
           ("CITE"    "_"  . "_")
           ("CMD"     "*"  . "*")
           ("DFN"     "*"  . "*")
           ("EM"      "~"  . "~")
           ("I"       "~"  . "~")
           ("Q"       "\"" . "\"")
           ("REMOVED" ""   . "")
           ("S"       ""   . "")
           ("STRONG"  "*"  . "*")
           ("SUB"     ""   . "")
           ("SUP"     ""   . "")
           ("U"       "_"  . "_")
          )
`w3-delimit-links'
     Put brackets around links?  If this variable is `eq' to
     `'linkname', then the link # is inserted after the link text.  If
     `nil', then nothing is done.  If it is non-`nil' and not `eq' to
     `'linkname', then [[ & ]] is inserted around the entire text of
     the link.  Is initially set to be `t' iff in normal Emacs.  `nil'
     if in Epoch or Lucid Emacs, since links should be in different
     colors/fonts.
`url-global-history-file'
     The global history file used by both Mosaic/X and Emacs-w3.  This
     file contains a list of all the URLs that have been visited.  This
     file is parsed at startup and used to provide URL completion.
`w3-hotlist-file'
     Hotlist filename.  This should be the name of a file that is
     stored in NCSA's Mosaic/X format (ncsa-mosaic-hotlist-format-1).
     It is used to keep a listing of commonly accessed URL's without
     having to go through 20 levels of menus to get to them.
`w3-personal-annotation-directory'
     Directory where Emacs-w3 looks for personal annotations.  This is
     a directory that should hold the personal annotations stored in a
     Mosaic-compatible format.
     (ncsa-mosaic-personal-annotation-log-format-1)
`url-pgp/pem-entity'
     The name by which the user is known to PGP and/or PEM entities.
     If this not set when w3-do-setup is run, it defaults to
     `(user-real-login-name)'@`(system-name)', which can often be wrong.
`url-personal-mail-address'
     Your full email address.  This is what is sent to HTTP/1.0 servers
     as the FROM field.  If this is not set when `w3-do-setup' is run,
     then it defaults to the value of `url-pgp/pem-entity'.
`w3-right-border'
     Amount of space to leave on right margin of WWW buffers.  This
     amount is subtracted from `(window-width)' for each new WWW buffer
     and used as the new fill-column.
`w3-track-mouse'
     Controls whether to track the mouse and message the url under the
     mouse.  If this is non-`nil', then a description of the hypertext
     area under the mouse is shown in the minibuffer.  This shows what
     type of link (inlined image, form entry area, delayed image,
     delayed MPEG, or hypertext reference) is under the cursor, and the
     destination.
`w3-use-forms-index'
     Non-`nil' means translate <ISINDEX> tags into a hypertext form.  A
     single text entry box is drawn where the ISINDEX tag appears.  If
     `t', the isindex handling is the same as Mosaic for X.
`url-use-hypertext-gopher'
     Controls how gopher documents are retrieved.  If non-`nil', the
     gopher pages are converted into HTML and parsed just like any other
     page.  If `nil', the requests are passed off to the `gopher.el'
     package by Scott Snyder.  Using the `gopher.el' package loses the
     gopher+ support, and inlined searching.
`url-wais-gateway-port'
     The port # of the WAIS gateway to pass all wais:// requests to.
     *Note Native WAIS Support::
`url-wais-gateway-server'
     The machine name where the WAIS gateway lives.  *Note Native WAIS
     Support::
`url-xterm-command'
     Command used to start a windowed shell, similar to an xterm.  This
     string is passed through `format', and should expect four strings:
     the title of the window, the program name to execute, and the
     server and port number.  The default is for xterm, which is very
     unix-centric, but is the most common case.
File: w3,  Node: Firewalls,  Next: Proxy Gateways,  Prev: Basic Setup,  Up: Setting Up
Firewalls
=========
   There are several different reasons why you may need to use the
gateway support in Emacs-w3.
  1. You are behind a firewall.  This is usually the case at large
     corporations with moderately paranoid system-administrators.
  2. You are using TERM (1) for slip-like access to the internet.
     NOTE: Emacs 19.22 has patches to enable native TERM networking, to
     enable it, #define TERM in the appropriate s/*.h file for your
     operating system, then change the SYSTEM_LIBS define to include
     the `termnet' library that comes with the latest versions of TERM.
  3. For some reason your version of Emacs can't resolve hostnames.
     This happens quite often on Sun workstations and some ultrix
     machines.  Some C libraries do not include the hostname resolver
     routines in their static libraries.  If Emacs was linked
     statically, this means it won't be able to get to any machines off
     your local net.  This is characterized by being able to reach
     someplace with a raw ip number, but not its hostname
     (http://129.79.254.191/ works, but http://www.cs.indiana.edu/
     doesn't).
     If for some reason your system administrator will not recompile
     Emacs with the `-lresolv' library or dynamic linking, you need to
     act as if you were behind a firewall.
  4. You are running Lucid Emacs 19.x and Solaris 2.x (SunOS 5.x).  For
     some reason, network processes under Solaris and Lucid Emacs never
     get a status of `exit' or `closed'.  This causes retrieval of HTTP
     and gopher pages to hang indefinitely, with Emacs chewing up large
     amounts of your CPU time.
     NOTE: You do not need to use gateways anymore for this problem.
     With the release of Lucid Emacs 19.10, this problem is fixed if you
     #define FIX_SOLARIS_W3_BUG somewhere in your config.h or s/*.h
     configuration file.  This will be in the stock 19.11 release of
     XEmacs
   Emacs-w3 has support for using the gateway mechanism only for
certain domains.  To use this, you must change the value of
`url-gateway-local-host-regexp'.  This should be a regular expression
(2) that matches local hosts that do not require the use of a gateway.
If `nil', then all connections are made through the gateway.
   Emacs-w3 supports several methods of getting around gateways.  The
variable `url-gateway-method' controls which of these methods is used.
This variable can have several values (use these as symbol names, not
strings):
"program"
     Run a program in a subprocess to connect to remote hosts (examples
     are itelnet(3), an expect(4) script, etc.).
"host"
     This allows you to log into another local computer that has access
     to the internet, and run a telnet-like program from there.
"tcp"
     Masanobu UMEDA [e-mail] has written a very nice
     replacement for the standard networking in Emacs.  This does
     basically the same thing that a method of `program' does, but is
     slightly more transparent to the user.
"native"
     This means that Emacs-w3 should use the builtin networking code of
     Emacs.  This should be used only if there is no firewall, or
     someone at your site has already hacked the Emacs source to get
     around your firewall.  Two of these need a bit more explanation
than that: If you are running a program in a subprocess to emulate a
network connection, you need to set a few extra variables.  The variable
`url-gateway-telnet-program' should point to an executable that accepts
a hostname and port # as its arguments, and passes standard input to
the remote host.  This can be either the full path to the executable or
just the basename.  The variable `url-gateway-telnet-ready-regexp'
controls how long Emacs-w3 should wait after spawning the subprocess to
start sending to its standard input.  This gets around a bug where
telnet would miss the beginning of requests becausse it did not buffer
its input before opening a connection.  This should be a regular
expression to watch for that signifies the end of the setup of
`url-gateway-telnet-program'.  The default should work fine for telnet.
   If you are using the `host'-based gatway method, things get a bit
more complicated.  This is basically my attempt to do some of the basic
stuff of expect within elisp.  First off, set the variable
`url-gateway-host' to be the name of your gateway machine.
   The variable `url-gateway-host-program' controls how the host is
reached.  The easiest way is to have a program that does not require a
username and password to allow you to login.  The most common of these
is the "rsh" command.
   If you do not have rsh, then things get very ugly.  First, set the
variable `url-gateway-program-interactive' to non-`nil'.  Then you need
to define the variables `url-gateway-host-username' and
`url-gateway-host-password' to be the username and password necessary
to log into the gateway machine.  The regular expressions in the
variables `url-gateway-handholding-login-regexp' and
`url-gateway-handholding-password-regexp' should match the login and
password prompts on the gateway system respectively.  For example:
     (setq url-gateway-host-program "telnet"
           url-gateway-program-interactive t
           url-gateway-host-username "wmperry"
           url-gateway-host-password "yeahrightkeepdreaming"
           url-gateway-host "moose.cs.indiana.edu"
           url-gateway-host-program-ready-regexp "Escape character is .*"
           url-gateway-handholding-login-regexp "ogin:"
           url-gateway-handholding-password-regexp "ord:")
   This should take care of you logging into the remote system.  The
variable `url-gateway-host-prompt-pattern' should contain a regular
expression that matches the shell prompt on the remote machine.  This
should appear no where in the login banner/setup, or things could get
very confused.
   Now you are ready to actually get off of your local network!  The
variable `url-gateway-host-program-ready-regexp' should contain a
regular expression that matches the end of the setup of
`url-gateway-host-program' when it tries to make a connection to an
off-firewall machine.  (Basically the same as
`url-gateway-telnet-ready-regexp'.
   Now you should be all set up to get outside your local network.  If
none of this makes sense, its probably my fault.  Please check with your
network administrators to see if they have a program that does most of
this for you already, since somebody somewhere at your company has
probably been through something similar to this before, and would be
much more helpful/knowledgeable about your local setup than I would be.
But feel free to mail me as a last resort.
   ---------- Footnotes ----------
   (1)  TERM is a user-level protocol for emulating IP over a serial
line.  More information is available at
sunsite.unc.edu:/pub/Linux/apps/comm/term
   (2)  Please see the full Emacs distribution for a description of
regular expressions
   (3)  Itelnet is a standard name for a telnet executable that is
capable of escaping the firewall.  Check with your system
administrators to see if you have anything similar
   (4)  Expect is a scripting language that allows you to control
interactive programs (like telnet) very easily.  It is available from
gatekeeper.dec.com:/pub/GNU/expect-3.24.0.tar.gz
File: w3,  Node: Proxy Gateways,  Next: Basic Usage,  Prev: Firewalls,  Up: Setting Up
Proxy Gateways
==============
   In late January, Kevin Altis and Lou Montulli proposed and
implemented a new proxy service.  This service requires the use of
environment variables to specify a gateway server/port # to send
protocol requests to.  Each protocol (http, wais, gopher, ftp, etc.)
can have a different gateway server.  The environment variables are
PROTOCOL_proxy, where PROTOCOL is one of gopher, telnet, file, http,
ftp, tn3270, news, mailto, www, or wais.
   The main thing to understand about the proxy gateway is that instead
of a partial URL being sent to the HTTP server, which is what we do
today when a client talks directly to an HTTP server, a client must
send a full URL (http://..., gopher://..., ftp://...) to the proxy
gateway server, the rest of the HTTP message is the same. For gopher
and ftp, the proxy gateway server returns the data encapsulated as a
MIME content type to the client like a normal HTTP message. HTTP MIME
content types are returned for all URL requests, regardless of the
protocol type of the URL. FTP directories, Gopher directories, etc. are
returned as text/html.
File: w3,  Node: Basic Usage,  Prev: Proxy Gateways,  Up: Top
Basic Usage
***********
   Emacs-w3 is similar to the Info package all Emacs users hold near
and dear to their hearts (*Note Info: (info)Top, for a description of
Info).  Basically, `space' and `backspace' control scrolling, and
`return' or `mouse2' follows a hypertext link.  The `f' and `b' keys
maneuver around the various links on the page.
   On non-graphic terminals (vt100, DOS, etc.), or with a graphics
terminal and old versions (18.xx) of Emacs, hypertext links are
surrounded by '[[' and ']]' by default.  On a graphics terminal with
newer versions of Emacs (epoch, lucid, or FSF 19), the links are in
bold print.  *Note Controlling Formatting:: for information on how to
change this, or for help on getting the highlighting to work on graphics
terminals.
   There are approximately 50 keys bound to special Emacs-w3 functions.
The basic rule of thumb regarding keybindings in Emacs-w3 is that a
lowercase key takes an action on the current document, and an uppercase
key takes an action on the document pointed to by the hypertext link
under the cursor.
   There are several areas that the keybindings fall into: movement,
information, action, and miscellaneous.
* Menu:
* Movement::        Moving around in a Emacs-w3 buffer
* Information::        Getting information about the Emacs-w3 document you
            are viewing, and/or links within that document.
* Action::        Taking actions in a Emacs-w3 buffer (following links,
            printing, etc.)
* Miscellaneous::    Miscellaneous keybindings
File: w3,  Node: Movement,  Next: Information,  Prev: Basic Usage,  Up: Basic Usage
Movement
========
`SPC'
     Scroll downward in the buffer.  With prefix arg, scroll down that
     many screenfuls.
`DEL'
     Scroll upward in the buffer.  With prefix arg, scroll up that many
     screenfuls.
`<, M-x w3-start-of-document'
     Go to start of document
`>, M-x w3-end-of-document'
     Go to end of document
`b, M-x w3-back-link'
     Attempts to move backward one link area in the current document.
     Signals an error if no previous links are found.
`M-x w3-show-hotlist'
     A hypertext listing of the items in the hotlist is generated on
     the fly, and the links can be followed normally.
`H, M-x w3-use-hotlist'
     Possibly go to a link in the hotlist.  A new buffer is created for
     the new document.
`m, M-x w3-complete-link'
     Choose a link from the current buffer and follow it.  A
     completing-read is done on all the links, so `space' and `TAB' can
     be used for completion.
`f, n, M-x w3-forward-link'
     Attempts to move forward one link area in the current document.
     Signals an error if no more links are found.
File: w3,  Node: Information,  Next: Action,  Prev: Movement,  Up: Basic Usage
Information
===========
   These functions relate information about one or more links on the
current document.
`v, M-x url-view-url'
     This shows the URL of the current document in the minibuffer.
`V, M-x w3-view-this-url'
     This shows the URL of the hypertext link under point in the
     minibuffer.  If there is not a hypertext link under point, then it
     shows the type of form entry area under point.  If there is no
     form entry area under point, then it shows the inlined image's URL
     that is under point, if any.
`s, M-x w3-source-document'
     This shows the HTML source of the current document in a separate
     buffer.  The `buffer-name' is based on the document's URL.
`S, M-x w3-source-document-at-point'
     Shows the HTML source of the hypertext link under point in a
     separate buffer.  The `buffer-name' is based on the document's URL.
`k, C-k, M-x w3-save-url'
     This stores the current document's URL in the kill ring, and also
     in the current window-system's clipboard, if possible.
`K, M-x w3-save-this-url'
     Stores the URL of the document under point in the kill ring, and
     also in the current window-system's clipboard, if possible.
File: w3,  Node: Action,  Next: Miscellaneous,  Prev: Information,  Up: Basic Usage
Action
======
   First, here are the keys and functions that bring up a new hypertext
page, usually creating a new buffer.
`return'
     Pressing return attempts to follow the link under the cursor.
     With a prefix argument (`C-u'), this forces the file to be saved
     to disk instead of being passed off to other viewers or being
     parsed as HTML.
`button2, M-x w3-follow-mouse'
     This function expects to be bound to a mouse button.  It movess to
     the point under mouse and try to fetch the link that was clicked
     on.  If no link is found, a message is displayed in the minibuffer.
`C-button2, M-return, M-x w3-follow-inlined-image'
     This function tries to retrieve the inlined image that is under
     point.  It ignores any form entry areas or hyperlinks, and blindly
     follows any inlined image.  Useful for seeing images that are
     meant to be used as hyperlinks when you are not on a terminal
     capable of displaying graphics.
`m, M-x w3-complete-link'
     Does a completing-read on all the hypertext links in the current
     buffer.  Use `space' and `tab' to complete on the links.
`r, g, M-x w3-reload-document'
     This reloads the current document--the current buffer is killed,
     and the URL it was visiting is fetched and redisplayed.  Your
     position within the buffer remains the same (unless the document
     has changed since you last retrieved it, in which case it should
     be relatively close).
`C-o, M-x w3-fetch'
     This function prompts for a URL in the minibuffer, and attempts to
     fetch it.  If there are any errors, or Emacs-w3 cannot understand
     the type of link you requested, the errors are displayed in a
     hypertext buffer.
`o, M-x w3-open-local'
     Find a local file, interactively.  This prompts you for a local
     file name to open.  The file must exist, and may be a directory.
     If the requested file is a directory and `url-use-hypertext-dired'
     is `nil', then a dired-mode buffer is displayed.  If non`nil',
     then Emacs-w3 automatically generates a hypertext listing of the
     directory.  The hypertext mode is the default, so that all the
     keys and functions remain the same.
`M-s, M-x w3-search'
     Perform a search, if this is a searchable index.  This sends a
     string of the type `'URL?search-terms'' to the server this
     document was retrieved from.  Searching requires a server,
     Emacs-w3 can not do local file searching, as there are too many
     possible types of searches people could want to do.  The only URL
     types that allow searching are HTTP and X-EXEC
`C-c C-b, M-x w3-show-history-list'
     If `url-keep-history' is non-`nil', then Emacs-w3 keeps track of
     all the URLs you visit in an Emacs session.  This function takes
     all the links that are in that internal list, and formats them as
     hypertext links in a list.
   And here are the commands to move around between Emacs-w3 buffers:
`l, M-x w3-goto-last-buffer'
     Go to last WWW buffer visited
`q, M-x w3-quit'
     Quits WWW mode.  This kills the current buffer and goes to the most
     recently visited buffer.
`u, M-x w3-leave-buffer'
     This is similar to w3-quit, but the buffer is not killed, it is
     moved to the bottom of the buffer list (so it is the least likely
     to show up as the default with switch-to-buffer).
`B, M-x w3-backward-in-history'
     Take one step back along the path in the current history.  Has no
     effect if at the beginning of the history list.
`F, M-x w3-forward-in-history'
     Take one step forward along the path in the current history.  Has
     no effect if at the end of the history list.
File: w3,  Node: Miscellaneous,  Prev: Action,  Up: Basic Usage
Miscellaneous
=============
`M-m, M-x w3-mail-current-document'
     Mails the current document to someone.  Choose from 3 different
     formats to mail: formatted text, HTML source, or LaTeX source.
     When the HTML source is mailed, then an appropriate <base> tag is
     inserted at the beginning of the document so that relative links
     may be followed correctly by whoever receives the mail.
`M-M, M-x w3-mail-document-under-point'
     Mails the document pointed to by the hypertext link under point to
     someone.  Choose from 3 different formats to mail: formatted text,
     HTML source, or LaTeX source.  When the HTML source is mailed,
     then an appropriate <base> tag is inserted at the beginning of the
     document so that relative links may be followed correctly by
     whoever receives the mail.
`p, M-x w3-print-this-url'
     Prints the current document.  Choose from 3 different formats to
     print: formatted text, HTML source, or postscript (by using LaTeX
     and dvips).
     When the formatted text is printed, the normal `lpr-buffer'
     function is called, and the variables `lpr-command' and
     `lpr-switches' control how the document is printed.
     When the HTML source is printed, then an appropriate <base> tag is
     inserted at the beginning of the document.  When postscript is
     printed, then the HTML source of the document is converted into
     LaTeX source.  If the variable `w3-use-html2latex' is non-`nil',
     then the program specified by `w3-html2latex-prog' is run in a
     subprocess with the arguments in `w3-html2latex-args'.  The
     `w3-html2latex-prog' must accept HTML source on its standard input
     and send the LaTeX output to standard output.  If
     `w3-use-html2latex' is `nil', then an Emacs Lisp function uses
     regular expressions to replace the HTML code with LaTeX markup.
     The variable `w3-latex-docstyle' controls how the document is laid
     out in this case, and postscript figures are printed as well.
`P, M-x w3-print-url-under-point'
     Prints the document pointed to by the hypertext link under point.
     Please see the documentation for `w3-print-this-url' directly above
     for more information.
`M-x w3-insert-formatted-url'
     Insert a fully formatted HTML link into another buffer.  This gets
     the name and URL of either the current buffer, or, with a prefix
     arg, of the link under point, and construct the appropriate
     <a...>...</a> markup and insert it into the desired buffer.
`M-tab, M-x w3-insert-this-url'
     Inserts the URL of the current document into another buffer.
     Buffer is prompted for in the minibuffer.  With prefix arg, uses
     the URL of the link under point.
`U, M-x w3-use-links'
     Select one of the <LINK> tags from this document and fetch it.
     Links are attributes of a specific document, and can tell such
     things as who made the document, where a table of contents is
     located, etc.
     This allows you to follow the <link...> tags in the current
     document.  Link tags specify relationships between documents in
     two ways.  Normal (forward) relationships (where the link has a
     REL="xxx" attribute), and reverse relationships (where the link
     has a REV="xxx" attribute).  This first asks what type of link you
     want to follow (Normal or Reverse), then does a `completing-read'
     on only the links that have that type of relationship.
File: w3,  Node: Compatibility w/Mosaic,  Up: Top
Compatibility with NCSA Mosaic
******************************
   Since NCSA Mosaic for Xwindows is the de-facto hypertext browser at
most sites, Emacs-w3 is compatible with it in several ways.
* Menu:
* Hotlist Handling::            A hotlist is an easy way to keep track of
                interesting Web pages without having to
                remember the exact path to get there.
* Session History::             Keeping a history of where you have been
                in one Emacs sessions allows the use of
                'forward' and 'back' buttons easily.
* Global History::        Keeping a history of all the places you
                have visited on the web.
* Annotations::                 Annotations allow you to write comments
                on other people's Web documents without
                needing to change their document.
File: w3,  Node: Hotlist Handling,  Next: Session History,  Prev: Compatibility w/Mosaic,  Up: Compatibility w/Mosaic
Hotlist Handling
================
   In order to avoid having to traverse many documents to get to the
same document over and over, Emacs-w3 supports a "hotlist" like Mosaic.
This is a file that contains URLs and aliases.  You can quickly go to
any document in the Web, providing you've been there before and added
it to your hotlist.  The variable `w3-hotlist-file' determines where
this information is saved.  The structure of the file is compatible with
Mosaic's hotlist file, so this defaults to `~/.mosaic-hotlist-default'.
   Hotlist commands are:
`a, M-x w3-hotlist-add-document'
     This adds the current document to your hotlist, with the buffer
     name as its identifier.  Modifies the file specified by
     `w3-hotlist-file'.  If this is given a PREFIX-ARGUMENT (via
     `C-u'), the title is prompted for instead of automatically
     defaulting to the `buffer-name'.
`M-x w3-hotlist-refresh'
     This rereads the default hostlist file specified by
     `w3-hotlist-file'.
`d, M-x w3-hotlist-delete'
     Prompts for the alias of the entry to kill.  You may press the
     spacebar or tab key for partial completions.  Once you select the
     item to delete, the internal representation of the hotlist is
     updated, and the file specified by `w3-hotlist-file' is updated.
`M-x w3-hotlist-rename-entry'
     Some hotlist item names can be very unwieldy (`Mosaic for X level
     2 fill out form support'), or uninformative (`Index of /').  If
     you are not satisfied with how a specific item is labeled, you may
     change it by typing `M-x w3-rename-hotlist-entry'.  Prompts for
     the item to rename in the minibuffer--use the spacebar or tab key
     for completion.  After having chosen an item to rename, prompts
     for a new title until a unique title is entered.  Modifies the
     file specified by `w3-hotlist-file'.
`H, M-x w3-use-hotlist'
     Prompts you for the alias to jump to.  You may press the spacebar
     or tab key for partial completions.
`M-x w3-show-hotlist'
     This converts your hotlist into an ordered list and parse it as
     HTML.
File: w3,  Node: Session History,  Next: Global History,  Prev: Hotlist Handling,  Up: Compatibility w/Mosaic
History
=======
   NCSA Mosaic keeps track of the URLs you have followed from a page, so
that it can provide forward and back buttons to keep a path of URLs
that you can review easily.  If you set the variable `url-keep-history'
to `t', then Emacs-w3 keeps a list of all the URLs you visit in a
session.  To see a listing of your history for this session of
Emacs-w3, type `M-x w3-show-history' from any buffer, and Emacs-w3
generates an HTML document showing every URL you have visited since you
started Emacs (or cleared the history list), and then format it.  Any
of the links can be chosen and followed to the original document.  To
clear the history list, choose 'Clear History' from the 'Options' menu.
   Another twist on the history list mechanism is the fact that all
Emacs-w3 buffers remember what URL, buffer, and buffer position you
were at before jumping to this document, and also keeps track of where
you jump to from that buffer.  This means that you can go forwards and
backwards very easily along the path you took to reach a particular
document.  To go forward, use the function `w3-forward-in-history', to
go backward, use the function `w3-backward-in-history'.  These are
fairly stable functions, but may not work as expected all the time.
First, the buffer-list is used to look at the URL of every buffer, and
if it matches the item in the history list you are looking for, then it
is brought forward.  If no buffer containing the desired URL is found,
then the URL is fetched.  Then the desired position in the buffer is
searched for.
File: w3,  Node: Global History,  Next: Annotations,  Prev: Session History,  Up: Compatibility w/Mosaic
Global History
==============
   Mosaic supports the idea of a "history" of URLs the user has visited,
and it displays them in a different style than normal URLs.  If you set
the variable `url-keep-history' to `t', then Emacs-w3 keeeps a list of
all the URLs you visit in a session.  The file is automatically written
to disk when exiting emacs.  The list is added to those already in the
file specified by `url-global-history-file', which defaults to
`~/.mosaic-global-history'.
   If any URL in the list is found in the file, it is not saved, but new
ones are added at the end of the file.
   One of the nice things about keeping a global history files is that
Emacs-w3 can use it as a completion table.  When doing `M-x w3-fetch',
you can hit the `tab' or `space' keys to complete on a partial URL.
This is very useful, especially for very long URLs that you didn't add
to your hotlist, or for seeing all the pages from a particular web
server before choosing which you want to see.
File: w3,  Node: Annotations,  Next: Group Annotations,  Prev: Global History,  Up: Compatibility w/Mosaic
Annotations
===========
   Mosaic allows you to annotate documents.  You can type in comments
about the current document, and these annotations appear as a link to
your comments at the end of the document when you browse it in Mosaic.
The original file is not changed.  There are two types of annotations
supported in Mosaic, and both are supported by Emacs-w3 as well.
* Menu:
* Group Annotations::             Annotations accessible by everyone
* Personal Annotations::          Private annotations only you see
File: w3,  Node: Group Annotations,  Next: Personal Annotations,  Prev: Annotations,  Up: Annotations
Group Annotations
-----------------
   NOTE: The group annotation experiment has been terminated.  It will
be replaced with support on the server side for adding <LINK> tags to
documents.